The following is a detailed description of each of the entries in a Character Def file. For a more practical view, see the example below



• Sprite File
  
  
  This is the name of the Sprite File that contains the Sprite data a single Sprite Set for this Player Character. If the file is not stored in this folder, its path must be included. The path must be "relative", meaning that it must tell how to get to the file from this folder, not the "Root Directory".
  
  If this file does not yet exist, a "blank" Sprite Set will be created, containing only one blank frame, and the file will be created when the the Sprite Editor's save feature is used while this Player Character's Sprite Set is selected.
  
  
  
  
• Constants
  
  
  There must be at least 9 Constants assigned to a Player Character. These required constants control how the player is initialized when its Player Character is set, how the viewport is managed for the character when it is set to automatically update, and how a player follows inclines/declines on level or tiled object paths. If more constants are desired for use with scripts, the number of total Constants available must first be altered in the "Game Def" to reflect the number of user-defined Constants that will be used. All Characters in the same game must list the same number of Constants. The user-defined constants should be listed immediately below the required Constants. The 9 required Constants, which must appear first and in this order, are as listed:
  
  0 - _Player_InitFunc
  
  
  This value represents the ID number of the function to call when the Player Character is set. A normal ID value references a Player Common Function, however, prefixing the value with an "F", such as "F0", signifies that the value represents a function from this character's own Character Def Function Listing
  
  
  1 - _Player_VPScroll_Left
  2 - _Player_VPScroll_Right
  3 - _Player_VPScroll_Up
  4 - _Player_VPScroll_Down
  
  
  These values are used for automatic viewport update, and describe at what point on the screen, starting at the top-left corner, the player can be before the viewport automatically pans in any of the four directions by the speeds given below
  
  
  5 - _Player_VPX_Speed
  6 - _Player_VPY_Speed
  
  
  These values are used for automatic viewport update, and describe how fast the viewport is allowed to move when attempting to catch up to the player once he has passed any of the offset boundaries described above
  
  
  7 - _Player_SlopeTolerance_Floor
  8 - _Player_SlopeTolerance_Ceiling
  
  
  These values describe how many pixels a path may raise from a "floor" or fall from a "ceiling" before it is considered to be a "wall". If the rise or fall of the path in front of the player is less than or equal to these values, the player will continue to follow the path. If the rise/fall is greater than this value, the solidity in front of the player is considered to be a "wall", and he will not be allowed to move in this direction
  
  
  
  • User-defined Constants.....
    
    
    At this point, any user-defined constants that need to be declared should be listed here in the same way as the required Constants. The number of user-defined Constants that is listed in the Game Def must be equal to the number of Constants that are listed from this point on. All Characters must use the exact same number of Constants (Required and user-defined). These Constants may be accessed as part of the complete listing (beginning with the Required Constants at ID 0), or they may be accessed as their own listing (beginning with the first user-defined Constant at ID 0) if the lower-case "c" tag is used used. (See "Player Variables" Doc)
    
  
  
• Character's Custom Variables
  
  
  This section isn't an actual entry, but it is suggested that this area be used to enter comments that list the name, ID, and description of any user-defined variables that are used by scripts so that it can be used for reference.
  
  
  
• Sound Effects
  
  
  This is a listing of ID numbers of the sound effects that this character object can play. This HCGE build does not expect any required effects to be listed. If more sound effects are desired for use with scripts, the number of custom sound effects available for character use must be altered below to reflect number of user-defined sound effects that will be used
  
  
  • There are no sound effects required by this build of HCGE
    
    
  • Number of Custom Sound Effects
    
    
    If the player should use any Sound Effects that aren't required, this value specifies how many. If no extra sound effects are desired, this value should be 0. If it is greater than 0, the IDs for the custom Sound Effect listing should be listed immediately below in the same way as the required Sound Effects. This list may be accessed as part of the full Sound Effect listing (starting with the first required Sound at ID 0), or as a listing of its own (starting with the first Custom Sound Effect entry at ID 0) if the lower-case "s" tag is used when referencing its ID in a Script Function (such as "s0" for the first Custom Sound). This list is used by Script Commands that call for Player Sound Effects
    
  
  
• Movement Mode Properties
  
  
  This section is used to build "Movement Modes" for the character that describes how the player moves, animates, and reacts to input. The behavior is set up by the inclusion of the following data:
  
  
  • Movement Function
    
    
    The ID number of a player function that should be called during this character's Movement Phase, immediately after hard-coded path movement. In general, this function is responsible for controlling player velocities, and its reactions to level collisions, level events, and other player state triggers. A normal ID value references a function from this character's own Character Def Function Listing, however, prefixing the value with a "C", such as "C0", signifies that the value represents a Player Common Function
    
    
    
  • Update Function
    
    
    The ID number of a player function that should be called during this character's Update Phase, immediately before the player's Animation is processed, and the automatic viewport update is managed. In general, this function is responsible for controlling what Animation a player is playing relative to the movement mode and any special states, and to update automatic viewport properties or to manually update the viewport. A normal ID value references a function from this character's own Character Def Function Listing, however, prefixing the value with a "C", such as "C0", signifies that the value represents a Player Common Function
    
    
    
  • Number of Key Events
    
    
    The number of different key combinations that can trigger an event during this "Movement Mode". Each combination and its corresponding event are listed directly below:
    
    
    • Num of Keys
      
      
      The number of keypresses that this event requires to be triggered. Each key that must be pressed simultaneously for this event is listed directly below:
      
      
      • Key
        
        
        The ID number of the desired key's position in the raw Key State Table, or a mapped key. Placing the identifiers "H" (for "Held") or "T" (for "Tapped") directly in front of the value will cause the event to be retriggered every frame for as long as the key combination is being held, or only on the first frame when the combination was struck, respectively. To reference an entry from the Key Map corresponding to the current player rather than a raw key, place a "P" in front of the value and "H"/"T" identifiers. To reference an entry from a specific Key Map, place an "M" in front of the value and identifiers, followed by the ID number of the desired Key Map. (Ex: H56 PT2 M0H3)
        
      
      
    • Function
      
      
      The ID number of the player function that should be called if all keys for this event are pressed. A normal ID value references a function from this character's own Character Def Function Listing, however, prefixing the value with a "C", such as "C0", signifies that the value represents a Player Common Function
      
  
  
• Animation Func IDs
  
  
  This is a listing of ID numbers of the functions that this character should use for animation purposes. Animation is not limited to the functions shown in this list, but the entries in this list can be modified during gameplay to swap animations as needed. There must be at least 1 of these assigned to each character. If more animations are desired for use by scripts, the number of user-defined Animation Functions must be altered below to reflect the number of Animation Function IDs that will be added to the list. The 1 required animation, which must appear first, is:
  
  
  • Default
    
    
    This animation will run automatically when the Player Character is set
    
    
    
  • Number of Custom Animation Entries
    
    
    If more Animation ID entries are desired, this value specifies how many. If none, it should be set to 0. The Custom Animation list can be used to store animation IDs for use by scripts in cases such as when a Player's state changes, and it may also contain IDs that may be switched with other entries, so that when that entry is called for, a different animation may be played depending on other aspects of the Player's state. The desired Animation ID listing entries should appear immediately below in the same way as the required entries.
    
    This list may be accessed as part of the full Animation ID listing (starting with the first required Animation ID Entry at ID 0), or as a listing of its own (starting with the first Custom Animation ID Entry at ID 0) if the lower- case "l" tag is used when referring to its ID in a Script Function (such as "l0" for the first Custom Animation ID Entry). This list is used by Script Commands that call for or swap Player Animations
    
  
  
• Number of Player Funcs
  
  
  This is the number of scripted functions that will be listed for this character to use during animation, motion, etc. The Animation listing refers to the functions found in this listing, as do the player movement, update, and key events. The Functions themselves appear immediately below this line as described in their own documentation
  

The following is an example setup for a character def file to better demonstrate how to put the above information into practice. Use the same format and fill in the appropriate values given the information contained throughout the various documents to create a player character for an HCGE game

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; Example Character Def File ;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

Sprite File: chr0.spr


;-----------------------------------------------------------------;
;----------------Character's Constant Properties------------------;
;-----------------------------------------------------------------;
;Total number is defined in Game Def File

;The 9 Required Constants
  0 - Player_InitFunc:                    22 ;Common Func 22, Player Init/Sentry

  1 - Player_VPScroll_Left:              144
  2 - Player_VPScroll_Right:             160
  3 - Player_VPScroll_Up:                 96
  4 - Player_VPScroll_Down:               96
  5 - Player_VPX_Speed:                   16
  6 - Player_VPY_Speed:                   16

  7 - Player_SlopeTolerance_Floor:         4
  8 - Player_SlopeTolerance_Ceiling:       4

;The extra Constants just for this game
  0 - Example User Constant 0:          $600
  1 - Example User Constant 1:            $C


;-----------------------------------------------------------------;
;-----------------Character's Custom Variables--------------------;
;-----------------------------------------------------------------;
;These are just comments to document the custom variables used in scripts

; 0 - Example Custom Player Variable 0
; 1 - Example Custom Player Variable 1


;-----------------------------------------------------------------;
;-------------------Character's Sound Effects---------------------;
;-----------------------------------------------------------------;

;The 0 Required sounds
  ;There are currently no required sounds

;The extra sounds just for this game
Number of Custom Sound Effects:   2
  0 - Example Chr SFX 0:     1
  1 - Example Chr SFX 1:     2


;-----------------------------------------------------------------;
;--------------------Movement Mode Properties---------------------;
;-----------------------------------------------------------------;

Number of Movement Modes:   2

Mode 0 - Example Movement Mode 0
        Movement Function:C11  ;Character Common Function 11
          Update Function:C12  ;Character Common Function 12
     Number of Key Events:  2
    Event 0 - Num of Keys:  1  ;Example Player Key Event
                    Key 1:PH0  ;Hold Player Button 0
                 Function:C25  ;Character Common Function 25
    Event 1 - Num of Keys:  1  ;Example Player Key Event
                    Key 1:PT1  ;Tap Player Button 1
                 Function:C26  ;Character Common Function 26
Mode 1 - Example Movement Mode 1
        Movement Function:C13  ;Character Common Function 13
          Update Function:C14  ;Character Common Function 14
     Number of Key Events:  2
    Event 0 - Num of Keys:  1  ;Example Player Key Event
                    Key 1:PH0  ;Hold Player Button 0
                 Function:  2  ;This Character's Function 2
    Event 1 - Num of Keys:  1  ;Example Player Key Event
                    Key 1:PT1  ;Tap Player Button 1
                 Function:  3  ;This Character's Function 3


;-----------------------------------------------------------------;
;-------------------Animation Function Listing--------------------;
;-----------------------------------------------------------------;

;The 1 Required Animations
  0 - Default Animation:                 1 ; Used by this script for standing still

;The extra Animations just for this game
Number of Custom Animation Entries:    25

  1 - Example Custom Animation 1:        7 ;  l0	(This Character Function  7)
  2 - Example Custom Animation 1:       11 ;  l1	(This Character Function 11)
  3 - Example Custom Animation 1:        7 ;  l2	(This Character Function  7)


;-----------------------------------------------------------------;
;-----------Character's Animation and Action Functions------------;
;-----------------------------------------------------------------;

Number of Player Funcs: 2

;===================================================================================
;=======================================
;Function 0 - Example Player Function 0=
;=======================================

	#_FetchPlayer				
	:_Ref_All						
	:r_Curr_Player						

	#_Chr=Const				;Set the player's flags
	:A_Player_Flags						;(Chr2)
	:%11101011100						;(Const) Left/Right stop, VPCenter, FollowPath, UseVector, FollowCurves, RotateBounds

# End	;Terminate Function

;===================================================================================
;=======================================
;Function 1 - Example Player Function 1=
;=======================================
@0
	#_FetchPlayer				
	:_Ref_All						
	:r_Curr_Player						

	#_Chr++					;Move one pixel
	:A_Player_X_Pos						

	#_FuncBreak				;Break until next frame
	#_GoTo					;Re-run the function
	:  @0

# End	;Terminate Function